#!/usr/bin/perl -c

package PIPL::System::Path;
use 5.006;
our $VERSION = '0.01';

=head1 NAME

PIPL::System::Path - Find system paths for directories and devices

=head1 SYNOPSIS

  use PIPL::System::Path;
  $p = PIPL::System::Path->instance;
  $null = $p->devnull;
  $dir = $p->appdata || $p->home;

=head1 DESCRIPTION

This singleton class provides an information about standard system's
paths like home directory or null device.

=cut


use strict;

use base 'PIPL::Class::Base',
         'PIPL::Class::Singleton';


# List of class fields (name => {is=>ro|rw, default=>value})
use constant FIELDS => {
    appdata => { is => 'ro' },
    devnull => { is => 'ro' },
    home    => { is => 'ro' },
    root    => { is => 'ro' },
    tmpdir  => { is => 'ro' },
};


# Returns a string representation of the application data directory
sub appdata {
    my $self = shift; $self = __PACKAGE__->instance unless ref $self eq __PACKAGE__;
    return $self->{appdata} if defined $self->{appdata};

    my $appdata;
    require PIPL::System::Config;
    my $config = PIPL::System::Config->instance;
    if ($config->{osname} eq 'MSWin32') {
        eval { require Win32; };
        require PIPL::System::Env;
	my $env = PIPL::System::Env->instance;
        $appdata = (
		defined $Win32::VERSION
		&& Win32::GetFolderPath(Win32::CSIDL_APPDATA())
	    ) || $env->{APPDATA} || $env->{HOME} || '';
    }
    else {
        $appdata = '';
    }
    return $self->{appdata} = $appdata;
}


# Returns a string representation of the application data directory
sub home {
    my $self = shift; $self = __PACKAGE__->instance unless ref $self eq __PACKAGE__;
    return $self->{home} if defined $self->{home};

    require PIPL::System::Env;
    my $env = PIPL::System::Env->instance;
    my $home = $env->{HOME} || '';

    return $self->{home} = $home;
}


# Returns a string representation of the temporary directory
sub tmpdir {
    my $self = shift; $self = __PACKAGE__->instance unless ref $self eq __PACKAGE__;
    return $self->{tmpdir} if defined $self->{tmpdir};

    require File::Spec;
    return $self->{tmpdir} = File::Spec->tmpdir;
}


# Initialize singleton instance at start
__PACKAGE__->instance;


1;


=head1 BASE CLASSES

=over 2

=item *

L<PIPL::Class::Base>

=item *

L<PIPL::Class::Singleton>

=back

=head1 CONSTRUCTOR

=over

=item new

Create new object.

  $obj = new PIPL::System::Path;
  $home = defined $obj->{home} ? $obj->{home} : $obj->home;

=item instance

Return existing instance of class or create new object.

  $obj = instance PIPL::System::Path;
  $home = defined $obj->{home} ? $obj->{home} : $obj->home;

=back

=head1 METHODS

=over

=item appdata

Returns a string representation of the application data directory on Windows
system or empty string on non-Windows system.  It is usually the
F<C:\Program Files> directory.

  $d = PIPL::System::Path->appdata or die 'only for Windows';

=item home

Returns a string representation of the home directory.  It is usually the
same as B<$HOME> environment variable.

  $d = PIPL::System::Path->home;

=item tmpdir

Returns a string representation of the first writable directory from a
list of possible temporary directories.  Returns the current directory
if no writable temporary directories are found.  It is usually the F</tmp>
for Unix system.

  $d = PIPL::System::Path->tmpdir;

=back

=head1 SEE ALSO

L<PIPL::Class::Base>, L<PIPL::Class::Singleton>.

=head1 AUTHORS

Piotr Roszatycki E<lt>dexter@debian.orgE<gt>

=head1 LICENSE

Copyright 2006-2007 by Piotr Roszatycki E<lt>dexter@debian.orgE<gt>.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>
